worklog JQL Function Documentation

Overview

The worklog JQL function allows you to search for issues that have worklogs matching specific criteria, such as author, time period, or time spent. This function is useful for tracking logged work, auditing time entries, and analyzing worklog activity within your Jira instance.

Key Features

• Author Filtering: Filter worklogs by the user who logged the time.
• Time Period Filtering: Specify a start date and optional end date to focus on worklogs created within a specific time frame.
• Time Spent Filtering: Filter worklogs by minimum and/or maximum time spent using human-readable time expressions.
• Comprehensive Validation: Validates all input parameters to ensure accurate results and provide clear error messages.
• JQL Integration: Seamlessly integrates with Jira Query Language (JQL) for complex queries.

How to Use

To use the worklog function, construct a JQL query that includes the worklog function. The syntax is as follows:

issue in worklog("subquery", ["author"], ["start_date"], ["end_date"], [min_time_spent], [max_time_spent])

Parameters:

• subquery (required): A valid JQL query that defines the set of issues to evaluate.
• author (optional): The name of the user who logged the worklog.
• start_date (optional): The start date for the worklog period in format "yyyy/MM/dd HH:mm" or "yyyy/MM/dd".
• end_date (optional): The end date for the worklog period in the same format as start_date.
• min_time_spent (optional): Minimum time spent for a worklog to be included. Can be specified in the format "1d 2h 3m 4s" where:
  • d represents days
  • h represents hours
  • m represents minutes
  • s represents seconds
• max_time_spent (optional): Maximum time spent for a worklog to be included. Uses the same format as min_time_spent.

Examples:

1. Finding Issues with Any Worklogs:

   issue in worklog("project = CITEST")

2. Finding Issues with Worklogs by a Specific User:

   issue in worklog("project = CITEST", "John Smith")

3. Finding Issues with Worklogs in a Date Range:

   issue in worklog("project = CITEST", "", "2024/01/01", "2024/03/31")

4. Finding Issues with Worklogs with Minimum Time Spent:

   issue in worklog("project = CITEST", "", "", "", "1h 30m")

5. Finding Issues with Worklogs with Maximum Time Spent:

   issue in worklog("project = CITEST", "", "", "", "", "2h 15m")

6. Finding Issues with Worklogs in a Time Range:

   issue in worklog("project = CITEST", "", "", "", "30m", "2h")

Input and Output Details

• Input: The worklog function takes a subquery, an optional author name, optional start and end dates, and optional minimum and maximum time spent values.
• Output: The function returns a set of issues that have worklogs matching the specified criteria.

Error Handling

The function validates all input parameters and will return clear error messages for:

• Invalid date formats (must be "yyyy/MM/dd HH:mm" or "yyyy/MM/dd")
• Invalid time expressions (must follow the format "1d 2h 3m 4s")
• Negative time values
• Minimum time spent greater than maximum time spent
• Invalid JQL queries

Configuration and Dependencies

• Ensures compatibility with the Jira Expressions API
• Handles batched processing of issues to optimize performance and avoid API limits
• Coordinates with Jira's worklog system to track time entries

Performance Considerations

The function analyzes all worklogs from issues matching the JQL subquery. It may take a significant amount of time to complete for issues with many worklogs.

Conclusion

The worklog JQL function enhances the flexibility of Jira queries by allowing users to find issues based on their worklog history. This powerful tool can help teams track time spent, audit worklog entries, and analyze how work is being logged and distributed across issues.